Page Object 与 Screenplay 模式

// 典型的流水账脚本：业务意图被技术细节淹没
driver.findElement(By.name("username")).sendKeys("admin");
driver.findElement(By.name("password")).sendKeys("123456");
driver.findElement(By.id("login-btn")).click();
assert driver.getTitle().contains("Welcome");
driver.findElement(By.linkText("图书")).click();
driver.findElement(By.id("search-box")).sendKeys("软件测试");
driver.findElement(By.id("search-btn")).click();

// BasePage.java —— 基础页面类，封装通用能力
public abstract class BasePage {
    protected final WebDriver driver;
    private final WebDriverWait wait;

    protected BasePage(WebDriver driver) {
        this.driver = driver;
        // Selenium 4 推荐显式等待，最长 10 秒
        this.wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    }

    // 导航到指定 URL
    public void navigate(String url) { driver.get(url); }

    // 显式等待元素可见
    protected WebElement waitFor(By locator) {
        return wait.until(ExpectedConditions.visibilityOfElementLocated(locator));
    }

    // 截图用于失败排查
    public void takeScreenshot(String path) {
        File src = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE);
        try { Files.copy(src.toPath(), Paths.get(path)); } catch (IOException ignored) {}
    }
}

// LoginPage.java —— 登录页面对象
public class LoginPage extends BasePage {
    // 定位器集中声明，便于维护
    private final By username = By.id("username");
    private final By password = By.id("password");
    private final By loginBtn = By.id("login-btn");

    public LoginPage(WebDriver driver) { super(driver); }

    // 业务级方法：返回目标页面对象，实现类型安全的页面流
    public HomePage login(String user, String pwd) {
        waitFor(username).sendKeys(user);
        waitFor(password).sendKeys(pwd);
        waitFor(loginBtn).click();
        return new HomePage(driver);
    }
}

public class LoginPage extends BasePage {
    @FindBy(id = "username")        private WebElement usernameInput;
    @FindBy(id = "password")        private WebElement passwordInput;
    @FindBy(id = "login-btn")       private WebElement loginButton;

    public LoginPage(WebDriver driver) {
        super(driver);
        // 懒加载：仅在首次访问元素时查找，超时 5 秒
        PageFactory.initElements(
            new AjaxElementLocatorFactory(driver, 5), this);
    }
}

// components/HeaderComponent.ts —— TypeScript + Playwright 组件对象
import { Page, Locator } from '@playwright/test';

export class HeaderComponent {
  // 组件根节点，由外部传入，便于复用到不同页面
  constructor(private readonly root: Locator) {}

  get userMenu(): Locator {
    return this.root.locator('[data-testid="user-menu"]');
  }

  get logoutButton(): Locator {
    return this.root.locator('[data-testid="logout-btn"]');
  }

  // 业务操作：登出，返回登录页对象
  async logout(): Promise<void> {
    await this.userMenu.click();
    await this.logoutButton.click();
  }
}

// pages/SearchPage.ts —— 页面通过组合复用组件
export class SearchPage {
  constructor(private readonly page: Page) {}

  // 暴露 header 组件供测试用例调用
  get header(): HeaderComponent {
    return new HeaderComponent(this.page.locator('header'));
  }

  async search(keyword: string): Promise<void> {
    await this.page.locator('#search-box').fill(keyword);
    await this.page.locator('#search-btn').click();
  }

  // 供断言使用的查询方法：返回当前结果条数
  async resultCount(): Promise<number> {
    return this.page.locator('.result-item').count();
  }
}

// screenplay/Actor.ts —— 执行者
export class Actor {
  constructor(private readonly name: string, private abilities: Map<string, any> = new Map()) {}

  // 注册能力
  can<T>(ability: T, key: string = 'default'): this {
    this.abilities.set(key, ability);
    return this;
  }

  // 使用能力
  uses<T>(key: string = 'default'): T {
    return this.abilities.get(key);
  }

  // 执行任务
  attemptsTo(...tasks: Task[]): Promise<void> {
    return tasks.reduce(
      (p, task) => p.then(() => task.performAs(this)),
      Promise.resolve()
    );
  }

  // 提问：返回系统状态供断言
  asks<T>(question: Question<T>): Promise<T> {
    return question.answeredBy(this);
  }
}

// tasks/Login.ts —— 业务任务
export class Login implements Task {
  constructor(private user: string, private pwd: string) {}

  static with(user: string, pwd: string) { return new Login(user, pwd); }

  async performAs(actor: Actor): Promise<void> {
    const page = actor.uses<Page>('web');   // 取出浏览页面能力
    await page.locator('#username').fill(this.user);
    await page.locator('#password').fill(this.pwd);
    await page.locator('#login-btn').click();
  }
}

// questions/PageTitle.ts —— 状态提问
export class PageTitle implements Question<string> {
  async answeredBy(actor: Actor): Promise<string> {
    return actor.uses<Page>('web').title();
  }
}

// 测试用例：业务语义清晰，复用性高
const user = new Actor('已登录用户').can(page, 'web');
await user.attemptsTo(Login.with('admin', '123456'));
const title = await user.asks(new PageTitle());
expect(title).toContain('Welcome');

// 业务流程组合：登录→搜索→下单→登出
LoginFlow login = new LoginFlow(new LoginFlowParams("admin", "pwd"));
login.execute();

SearchBookFlow search = new SearchBookFlow(new SearchBookFlowParams("软件测试"));
search.withStartPage(login.getEndPage()).execute();

CheckoutBookFlow checkout = new CheckoutBookFlow(
    new CheckoutBookFlowParams(search.getOutput().getBookId()));
checkout.withStartPage(search.getEndPage()).execute();

// fixtures.ts —— Playwright 1.61
import { test as base, Page } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';
import { SearchPage } from './pages/SearchPage';

type Fixtures = {
  loggedInPage: Page;       // 已登录页面
  searchPage: SearchPage;   // 搜索页面对象
};

export const test = base.extend<Fixtures>({
  loggedInPage: async ({ page }, use) => {
    const loginPage = new LoginPage(page);
    await loginPage.navigate('https://example.com/login');
    await loginPage.login('admin', '123456');  // 复用 PO
    await use(page);
  },
  searchPage: async ({ loggedInPage }, use) => {
    await use(new SearchPage(loggedInPage));
  },
});

// 测试用例：声明式组合，无前置样板代码
test('搜索书籍', async ({ searchPage }) => {
  await searchPage.search('软件测试');
  expect(await searchPage.resultCount()).toBeGreaterThan(0);
});

// cypress/support/commands.js —— Cypress 15.x
import { LoginPage } from '../pages/LoginPage';

Cypress.Commands.add('loginViaPO', (user, pwd) => {
  const loginPage = new LoginPage(cy);
  return loginPage.login(user, pwd);  // 复用 PO 实现
});

// 测试用例
describe('购书流程', () => {
  it('登录后搜索', () => {
    cy.loginViaPO('admin', '123456');
    cy.get('#search-box').type('软件测试');
  });
});